/**
 * 文件：UserDAO.java
 * 作者：赵哲群
 * 完成度：完成
 * 最后修改日期：2023-7-2
 */
package com.gomokult.dao;

import com.gomokult.entity.User;
import com.gomokult.exception.IllegalOperationException;
import com.gomokult.exception.InvalidIDException;
import com.gomokult.exception.UserRegisteredException;

public interface UserDAO {
    /**
     * 增加用户：以电子邮箱{@code email}注册一个用户名为{@code nickname}，密码为{@code password}的账号。
     * @param email 注册账号所使用的邮箱
     * @param nickname 用户昵称
     * @param password 用户密码
     * @return 一个整数，表示数据库为该用户分配的ID,如果当邮箱{@code email}已被注册时。返回0
     */
    int insertrUser(String email, String nickname, String password);

    /**
     * 查找某用户是否存在：尝试使用密码{@code password}登录邮箱为{@code email}的账号。
     * @param email 账号的电子邮箱
     * @param password 用户输入的密码
     * @return 若登录成功，返回一个整数，表示该用户的ID；否则返回{@code 0}
     */
    int selectUser(String email, String password);

    /**
     * 获取ID为{@code userID}的用户的个人信息（不包含密码字段）。
     * @param userID 待查询的用户ID
     * @return 一个{@code User}对象，记录了目标用户的个人信息。为了保证账户安全，{@code User.password}属性应始终为{@code null}，如果id不存在或无效，返回null
     */
    User selectUserbyID(int userID) ;

    /**
     * 以ID为{@code executor}的用户身份更新用户信息。此方法接收一个用户对象{@code pattern}，然后将ID为{@code pattern.userID}的用户信息更新为{@code pattern}中的属性值。<p>
     * * 注意，此方法只能修改用户的个人信息。{@code winGamesCount}、{@code totalGamesCount}等由系统维护的无关属性将被忽略；{@code password}等涉及账号安全的属性也作忽略处理。
     * @param executorID 执行修改操作的用户的ID。该参数是原本是为了能够让管理员也可以修改用户信息。但由于管理员系统在进一步的需求分析中被弃用，该参数目前只起到验证操作的执行者是否为用户本身的作用。如果{@code executorID}与{@code pattern}中所描述的ID字段不一致，则抛出{@code IllegalOperationException}
     * @param pattern 记录了需要被修改成的用户信息，其ID字段表示需要被修改信息的用户
     * @throws InvalidIDException 当给定的ID无效或不存在时
     * @throws IllegalOperationException 当用户不具备修改指定用户个人信息的能力时
     * @throws UserRegisteredException 当用户填写的邮箱已被注册时
     */
    void updateUser(int executorID, User pattern) throws InvalidIDException, IllegalOperationException, UserRegisteredException;
    /**
     * 删除ID为{@code userID}的用户的个人信息。
     * @param userID 待查询的用户ID
     */
    void deleteUser(int userID) throws InvalidIDException;
    /**
     * 获取邮箱为{@code email}的用户的个人信息（不包含密码字段）。
     * @param email 待查询的用户邮箱
     * @return 一个{@code User}对象，记录了目标用户的个人信息。为了保证账户安全，{@code User.password}属性应始终为{@code null}
     * @throws InvalidIDException 当邮箱无效或不存在时
     */
    User selectUserbyEmail(String email) throws InvalidIDException;
    /**
     * 查询所有用户中的最高分
     * @return 所有用户中的最高分
     */
    int selectBestscore();
}
